KernelCAD Documentation

Patch Programming Tutorial demonstrates incorporation of KernelCAD ActiveX control into a simple dialog-based application using Visual C++ and Microsoft Visual Studio 6.0. Source code for Patch tutorial is available in Samples\Tutorials\VC\Patch folder of the installation directory. It is recommended to copy whole VC directory to location outside of the installation folder before loading or compilation. Patch is an MFC dialog-based application which displays a DInsight model consisting of a single patch of surface using KernelCAD ActiveX control and allows to modify geometrical parameters of the model.

Running the Application

Patch application loads ArcPatch.glm located in the Models folder of the installation directory. The dialog displays parameters, which can be modified to assign any shape valid for a model with single cross-sectional element (See Elements). To be able to compare behavior, two edges of ArcPatch.glm are not of the same type. The first edge (the right one) consists of arcs. The second edge consists of straight line elements. The first edit box "Cross-section position" specifies z coordinate for cross-sectional plane where all other parameter modifications will be applied. The next four edit boxes allow modification of coordinates of edge in the cross-section plane. Note that type of modifications is different depending whether the cross-section position is at the end ( z=0 or z=10 ) or anywhere in the middle of the axial range.

Note that curvature can be negative. Valid range for the curvature is [-cMax, cMax], where cMax is 1/ (half distance between the edges at the current cross-section)

To enter new value of the parameters press "Apply" button. If entered values are valid, the model will change in 3D.

Step 1. Creating the project

Open Visual Studio. Select File > New > Project in the menu. In Projects tab select MFC AppWizard(exe). Enter "Patch" in the Project Name edit box on the right. Select location for the project folder and click OK.

In Step 1 of the application wizard select "Dialog based" and click "Next". In the step 2 clear "About box" and press "Finish" to accept defaults for all other settings. The project will be created and the main dialog will be opened in resource editor.

Delete "TODO.." label in the center of the dialog. Adjust size of the dialog to 400x250 (the size is displayed at the bottom in the right hand pane of the status bar). Move "OK" and "Cancel" buttons to the bottom of the dialog.

Step 2. Inserting the KernelCAD component

In the menu select Project > "Add to Project" > "Components and controls". In the opened dialog double-click "Registered ActiveX Controls" and select "KernelCAD Control". Press Insert button. Press OK to confirm insertion of the component. In "Confirm Classes" dialog press OK to accept defaults. Close "Components and Controls Gallery" dialog. At this stage icon of the control should appear in the controls palette (if the palette in hidden right-click on the menu bar outside all options and select "Controls"). n addition to that files kernelcad.cpp and kernelcad.h should be added to the project and CKernelCAD class should appear in the "Class View" tab of the Project View.

Opening CKernelCAD node in the Class View will display available methods and properties of the control. (See also Properties and Methods )

Select the KernelCAD control in the controls palette and position it on the left in the dialog. The control should display default model Cube.glm.

Right-click on the control and select "Properties". In the opened Properties dialog open Control tab. Click "Browse" button and select ArcPatch.glm in the Models folder of the installation directory, which is "C:\Program Files\DInsight" by default.

On Render page of the dialog turn "Show global axes" check box on and select background color you like using the "Modify" button.

Click "Save All" button in the tool bar. Select Build Patch.exe from Build submenu. Press F5 key to run the application. Check that the model can be rotated (left mouse button). Pan (shift + left mouse button) and zoom (right mouse button) should work too.

Step 3. Programming access to the model

Let us create a variable of type CKernelCAD in the main dialog class of the project to get programmatic access to the control. Open Class Wizard (View > "Class Wizard" in the Visual Studio menu). Open "Member Variables" tab, select IDC_KERNELCADCTRL1 in the list and press "Add Variable" button. In the "Member Variable Name" edit box type m_ctrlCAD and press OK. Variable m_ctrlCAD will appear under CPatchDlg in the Class View.

Next we will get access to the IModel interface implemented by the control. Double-click OnInitDialog() node under CPatchDlg in the Class View. Replace "// TODO:" line with the next one:

IModel * pIModel = (IModel*)m_ctrlCAD.GetModel(); //(A)

Now we have access to the root interface, from which all other interfaces can be queried. The next step is obtain access to ISection interface of the first (and only) object in the model. In this application it is make sense to store the interface pointer in a dialog's variable. Generally storing interface pointers should be done with caution as the object can be volatile and after some manipulations the pointer cam quickly become invalid and its usage can cause access violations and other problems.

Right-click on the CPatchDlg node in the Class View and select "Add Member Variable". Enter ISection* for the type and m_pISection for the name. Press OK. The header file PatchDlg.h now will contain line :

ISection * m_pISection;

Add line

m_pISection = NULL;

to constructor of CPatchDlg .

In OnInitDialog() enter the next line just below the line (A):

pIModel->GetSection(0, &m_pISection); //(B)

Note that in a real life application prior to the previous call it is necessary to verify that the model contains at least one object with the help of IModel::GetSectionCount(). Other available methods of IModel and all other interfaces can be found either in this documentation (See Interface List) or directly from file Samples\VC\Include\DIInterface.h in the installation folder.

Step 4. Accessing Surface of the Object.

We need to retrieve another interface, which will be stored permanently in a dialog's variable. It is the IStrip interface. For objects of this type (Generic 3D Section) IStrip acts as a container of joined surface patches, of which the object's surface consists. In this case the model consists of a single patch.

Add a public variable m_pIStrip of IStrip* type to the dialog with a line

IStrip * m_pIStrip;

in the PatchDlg.h and set its value to NULL in the dialog constructor.

To retrieve the interface add line

m_pISection->QueryInterface( IID_IStrip, (void**)&m_pIStrip); //(C)

below the line (B) in the CPatchDlg::OnInitDialog() function.

Before compiling the project it is necessary to add reference to definition of KernelCAD interfaces. C++ definitions are contained in file Samples\VC\Include\DIInterface.h file. The best place for it is the StdAfx.h file.

Add line

#include "C:\Program Files\DInsight\Samples\VC\Include\DIInterface.h"

To StdAfx,h file just before the line //{{AFX_INSERT_LOCATION}}.

Build the project (F7 key) to make sure that no compilation errors where introduced so far.

Step 5. Accessing the base.

To be able to retrieve z-extents of the object and modify the current cross-section position it is needed to obtain IAxiBase interface.

Add line

IAxiBase * m_pIAxiBase;

to the main dialog header file and set the variable to NULL in the constructor.

Add line

m_pISection->QueryInterface( IID_IAxiBase, (void**)&m_pIAxiBase);

to the CPatchDlg::OnInitDialog() function next to line (C).

Step 6. Obtaining parameters of the object

Here we will get access to geometrical parameters of the only object in the model and display them in controls of the dialog.

Open the dialog in resource editor and place an edit box with id IDC_EDIT_ZCROSSPOSN in the top right hand corner. Add label "Cross-section position:" next to it.

Bind this edit box to variable m_dZCrossPosn of double type using "Member variables" page of the Class Wizard. Change its initial value in the dialog constructor to 5.0.

Let us separate obtaining access to edges of the patch into a different function.

Add new void function UpdateSurfaceInfo() to the dialog class using right-click on the class in the Class View or otherwise.

At the beginning of the function add line

m_pIAxiBase->SetCrossPosition( m_dZCrossPosn ); // (D)

which sets the current crosos-section position in the KernelCAD component at position currently entered in the dialog.

Add definitions

IElement * m_pIElemEdge1;
IElement * m_pIElemEdge2;
IElement * m_pIElemPatch;

next to definition of m_pIAxiBase in the PatchDlg.h header file and set them to NULL in the constructor. IElement interface manages parameters of basic geometric primitives. In this case elements are lines of two (right and left, see Surface Patches topic) edges and the adjoined surface patch represented by m_pIElemSegment.

Enter another two lines

m_pIStrip->GetElement(0, false, &m_pIElemEdge1);
m_pIStrip->GetElement(1, false, &m_pIElemEdge2);

just below the line (D). They will obtain IElement interfaces of the edges.

The last line in the function will be:

m_pIStrip->GetElement(0, true, &m_pIElemPatch);

which will retrieve IElement interface of the surface patch.

Add call to the implemented function UpdateSurfaceInfo() in the end of CPatchDlg::OnInitDialog().

Add remaining controls to the dialog so that it looks like:

Create variables m_dX1, m_dY1, m_dX2, m_dY2 and m_dCurvature of double type and bind them to the correspondent edit boxes.

Create another void function UpdatePage() in the dialog. Whenever necessary, this function will update information displayed by the dialog.

Copy the code below and paste into the function's body

m_pIElemEdge1->GetParam(0, &m_dX1);
m_pIElemEdge1->GetParam(1, &m_dY1);

m_pIElemEdge2->GetParam(0, &m_dX2);
m_pIElemEdge2->GetParam(1, &m_dY2);

m_pIElemPatch->GetParam(0, &m_dCurvature);

UpdateData(FALSE);

Edge1 is a line, which at the current z cross-section position gives a point, x and y coordinates of which are retrieved by the first two calls to GetParam() methods of IElement interface.

The last call to GetParam() retrieves the only parameter of the surface patch, namely radius of cross-sectional arc. UpdateData() is a standard MFC library function, which updates controls with new values of the bound variables.

Add call to UpdatePage() to the end of CPatchDlg::OnInitDialog().

In the end of CPatchDlg::OnInitDialog() add another line:

pIModel->Release();

It is important to release whenever an interface is no longer needed, otherwise a memory leak and sometimes more serious problems may occur.

Build the application and check that edit boxes display meaningful values.

Step 7. Programming modifications of the model

Here we will add code to update the model with new values of entered parameters.

Add a handler of Apply buttons clicks by holding Ctrl key and double-clicking the button in resource editor.

Fill the body of the handler with the code below:

UpdateData();

// Force cross position into valid range
if(m_dZCrossPosn<0.0)
m_dZCrossPosn = 0.0;
if(m_dZCrossPosn>10.0)
m_dZCrossPosn = 10.0;

m_pIAxiBase->SetCrossPosition( m_dZCrossPosn );

m_pIElemEdge1->SetParam(0, m_dX1) ;

m_pIElemEdge1->SetParam(1, m_dY1);

m_pIElemEdge2->SetParam(0, m_dX2);

m_pIElemEdge2->SetParam(1, m_dY2);

m_pIElemPatch->SetParam(0, m_dCurvature);

m_ctrlCAD.UpdateSurface();

UpdatePage();

Invalidate(FALSE);
UpdateWindow();

UpdataData() here is an MFC function which will copy contents of edit boxes into correspondent variables. For simplicity we have hard coded here actual minimal and maximal z coordinates in the model.

SetParam() calls make actual changes in the model. In real application it is necessary to check that all call succeeded and returned S_OK. Failure is quite common and does means only that the parameter value was rejected by the software because it would make impossible the geometry, like an attempt to make ends of an arc too far for the given radius or attempt to make radius too small for the given distance between the ends.

UpdateSurface() call is needed to recalculate the surface after changes in the geometry.

The last two calls is the standard MFC way to make the control to redraw itself.

Step 8. Cleanup

Add virtual destructor to the declaration of the dialog. Add the code below to the implementation file, so that the destructor looks like:

CPatchDlg::~CPatchDlg()
{
        if(m_pIElemPatch)
            m_pIElemPatch->Release();

        if(m_pIElemEdge1)
            m_pIElemEdge1->Release();

        if(m_pIElemEdge2)
            m_pIElemEdge2->Release();

        if(m_pIStrip)
            m_pIStrip->Release();

        if(m_pIAxiBase)
            m_pIAxiBase->Release();

        if(m_pISection)
                m_pISection->Release();
}

Step 9. Testing the application

Try to enter different values in the edit boxes and observe how the geometry of the model changes. Note that the result depends dramatically on whether the cross position is at the end of z (base ) range, namely 0.0 and 10.0 or anywhere in the middle.

Note also that when the cross-section position is inside the range, left and right hand edges behave differently because the right hand edge is a curve and the left hand one is a straight line. This can be verified using 3D Debugger.